home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / uw_1.exe / UW_HELP3.HLP < prev    next >
Text File  |  1992-11-03  |  23KB  |  666 lines
  1. `co(4,7);──────────────────────── /// The Keyboard/Mouse ──────────────────────────────`co();
  2.  
  3.  ┌──────────────────────────────────────────────────────────────────────────┐    
  4.  │        `keyword(init_mouse,/// init_mouse);              `keyword(end_mouse ,/// end_mouse);            `keyword(m_reset     ,/// m_reset);        │
  5.  │        `keyword(set_idle_func,/// set_idle_func);           `keyword(set_key_func,/// set_key_func);          `keyword(get_key     ,/// get_key);        │
  6.  │        `keyword(wait_event,/// wait_event);              `keyword(event_pending,/// event_pending);         `keyword(m_pos    ,/// m_pos);           │
  7.  │        `keyword(wait_ticks,/// wait_ticks);              `keyword(check_key ,/// check_key);            `keyword(m_released  ,/// m_released);        │
  8.  │        `keyword(m_hide,/// m_hide);                  `keyword(m_show    ,/// m_show);            `keyword(m_motion     ,/// m_motion);       │
  9.  │        `keyword(m_moveto,/// m_moveto);                `keyword(m_pressed ,/// m_pressed);            `keyword(m_ratio      ,/// m_ratio);       │
  10.  │        `keyword(m_colrange,/// m_colrange);              `keyword(m_rowrange,/// m_rowrange);                                │
  11.  │        `keyword(m_lpen_on,/// m_lpen_on);               `keyword(m_lpen_off,/// m_lpen_off);                                │
  12.  └──────────────────────────────────────────────────────────────────────────┘
  13.  
  14.         The UltraWin library interfaces to the user through either the keyboard,
  15.     mouse, or both.  The keyboard routines support all possible key presses
  16.     which include left and right Shift, Alt, and Ctrl key combinations.  The
  17.     mouse routines allow complete control of a two or three button mouse, and
  18.     is Microsoft driver compatible.    The event routines handle detecting both
  19.     mouse and keyboard presses for you, so making your programs support a
  20.     mouse is a snap!  In addition, UltraWin allows you to define your own
  21.     background function, which is called any place in the library that waits
  22.     for user input.  This allows you to write your own processing routines to
  23.     be performed in the background, then call one function to notify the
  24.     library of your routine, then just forget all about it!  Refer to the
  25.     set_idle_func and wait_event functions for details.
  26.  
  27. `co(10,1);/// init_mouse`co();   `keyword(source,[UW_EVENT.C]~init_mouse);
  28.         Call this function just after init_video or force_video if you wish to
  29.     use the mouse in your program.  If the mouse is connected and a driver is
  30.     installed, then the global variable Mouse_exists is set to TRUE (1). In
  31.     addition the mouse cursor column and row ranges are set to cover the
  32.     entire text screen.    After calling this function you may show the mouse on
  33.     the screen using the function m_show.
  34.  
  35. Prototype:
  36.     void init_mouse(void);
  37.  
  38. Parameters:
  39.     None.
  40.  
  41. Usage:
  42.     init_mouse();
  43.  
  44. `co(10,1);/// end_mouse`co();   `keyword(source,[UW_EVENT.C]~end_mouse);
  45.         If the mouse was found to be present in init_mouse, this function turns
  46.     the mouse back off.  This keeps the mouse from being active at the DOS
  47.     prompt.  Call this prior to exiting your program if your program called
  48.     init_mouse or the lower level m_reset function.
  49.  
  50. Prototype:
  51.     void end_mouse(void);
  52.  
  53. Parameters:
  54.     None.
  55.  
  56. Usage:
  57.     end_mouse();
  58.  
  59. `co(10,1);/// m_reset`co();   `keyword(source,[UW_EVENT.C]~m_reset);
  60.         This is the lower level function called by both init_mouse and
  61.     end_mouse. It is used both to determine if the mouse exists, and also to
  62.     reset the mouse prior to program exit.
  63.     
  64. Prototype:
  65.     void m_reset(M_RESET *m)
  66.  
  67. Parameters:
  68. `co(11,1);    M_RESET *m`co();
  69.         A variable of type M_RESET.  Refer to the structures/globals topic for
  70.         information on the members of this structure.
  71.  
  72. Usage:
  73.     M_RESET m;
  74.     ...
  75.     m_reset(&m);
  76.  
  77. `co(10,1);/// set_idle_func`co();   `keyword(source,[UW_EVENT.C]~set_idle_func);
  78.         Allows you to define your own background process. Simply write your own
  79.     C function, keeping in mind that to remain responsive to the keyboard you
  80.     should keep your code tight and fast.  Then call set_idle_func with the
  81.     pointer to your function.
  82.  
  83. Prototype:
  84.     void set_idle_func( int (*func_ptr)(void) );
  85.  
  86. Parameters:
  87. `co(11,1);    int (*func_ptr)(void)`co();
  88.         A pointer to the function you wish to install as the idle function.
  89.         
  90. Usage:
  91.     process()
  92.     {
  93.         ...
  94.     }
  95.     ...
  96.     set_idle_func( process );
  97.  
  98. `co(10,1);/// wait_event`co();   `keyword(source,[UW_EVENT.C]~wait_event);
  99.         Waits until either a key is pressed, or a mouse button is clicked.    The
  100.     global variable Event will contain the information about the event.    If it
  101.     is a keyboard event, the key or combination of keys pressed is saved.  If
  102.     a mouse event, then the button that was pressed, how many times it was
  103.     pressed, and the x and y coordinate at which the press occurred is saved.
  104.  
  105.         While UltraWin waits for user input, it is free to perform background
  106.     processing.    If a user defined function has been installed with
  107.     set_idle_func, that function will be called during idle time.
  108.     
  109. Prototype:
  110.     void wait_event(void);
  111.  
  112. Parameters:
  113.     None.
  114.  
  115. Usage:
  116.     wait_event();
  117.  
  118. `co(10,1);/// event_pending`co();   `keyword(source,[UW_EVENT.C]~event_pending);
  119.         Checks for an event, and returns TRUE (1) if an event has occurred or
  120.     FALSE (0) if no event has occurred.    If an event has occurred, then the
  121.     information about the event, which includes the event type (keyboard or
  122.     mouse), the key and modifier, or the mouse location and button status is
  123.     returned in the global Event variable.  Refer to `keyword(Structures/Globals,[uw_help1.hlp]/// Structures/Globals); for
  124.     information about the EVENT structure and member names for extracting
  125.     this information.
  126.  
  127. Prototype:
  128.     int event_pending(void);
  129.  
  130. Parameters:
  131.     None.
  132.  
  133. Usage:
  134.     int status;
  135.     ...
  136.     status = event_pending();
  137.  
  138. `co(10,1);/// wait_ticks`co();   `keyword(source,[UW_EVENT.C]~wait_event);
  139.         Waits for a given number of system ticks.    There are 18.2 system ticks
  140.     per second.  If you have defined a background process with the
  141.     set_idle_func function, it will call your process function while it waits
  142.     for the given ticks to pass.  UltraWin now has enhanced timer support.
  143.     See `keyword(Timer/Sound Support,[uw_help6.hlp]/// Timer/Sound Support); for further details.
  144.     
  145. Prototype:
  146.     void wait_ticks( clock_t ticks );
  147.  
  148. Parameters:
  149. `co(11,1);    int ticks`co();
  150.         The number of system ticks to wait.  Be sure to pass this as a long or
  151.         cast your number to a clock_t.
  152.  
  153. Usage:
  154.     wait_ticks( 9L );
  155.     wait_ticks( (clock_t) 37 );
  156.  
  157. `co(10,1);/// check_key`co();   `keyword(source,[UW_EVENT.C]~check_key);
  158.         Checks to see if a key has been pressed, and returns the key without
  159.     pulling it out of the keyboard buffer.  The key value is returned (see
  160.     UW_KEYS.H for key defines).  If no key has been pressed, then check_key
  161.     will return FALSE (0).
  162.       You can "capture" any key by installing a function that is called by
  163.     check_key.  This is set by calling `keyword(set_key_func,/// set_key_func);.  Check key will
  164.     pass this function the key and modifier.  When the called function
  165.     returns, if 1 is returned, check_key acts as though no key was ever
  166.     hit, if a 0 is returned, the key is then passed through.  This is a
  167.     very useful, low-level way to supply "hot-keys" anywhere in your
  168.     program, even while entering data!
  169.  
  170. Prototype:
  171.     int check_key(void);
  172.  
  173. Parameters:
  174.     None.
  175.  
  176. Usage:
  177.     int key;
  178.     ...
  179.     key = check_key();
  180.  
  181. `co(10,1);/// set_key_func`co();   `keyword(source,[UW_EVENT.C]~set_key_func);
  182.         Allows you to define your own "hotkey" function. Simply write your own
  183.     "C" function, keeping in mind that to remain responsive to the keyboard you
  184.     should keep your code tight and fast.  Then call set_key_func with the
  185.     pointer to your function.  Your function is passed the key and key
  186.     modifier.  See `keyword(check_key,/// check_key); for more details.
  187.  
  188. Prototype:
  189.     void set_key_func( int (*func_ptr)(int, int) );
  190.  
  191. Parameters:
  192. `co(11,1);    int (*func_ptr)(int, int)`co();
  193.         A pointer to the function you wish to install as the key function.
  194.         
  195. Usage:
  196.     process(int key